<?php
/** 
 * 
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Map.php 14 2006-11-28 22:05:19Z rdff3 $
 */
 
/**
 *
 */ 
require_once( "lang/Object.php" );

/**
 * An object that maps keys to values. A map cannot contain duplicate keys; each key can map to at most one value.
 * 
 * This interface takes the place of the Dictionary class, which was a totally abstract class rather than an interface.
 * 
 * The Map interface provides three collection views, which allow a map's contents to be viewed as a set of keys, collection 
 * of values, or set of key-value mappings. The order of a map is defined as the order in which the iterators on the map's 
 * collection views return their elements. Some map implementations, like the TreeMap class, make specific guarantees as to 
 * their order; others, like the HashMap class, do not.
 * 
 * Note: great care must be exercised if mutable objects are used as map keys. The behavior of a map is not specified if 
 * the value of an object is changed in a manner that affects equals comparisons while the object is a key in the map. A 
 * special case of this prohibition is that it is not permissible for a map to contain itself as a key. While it is permissible 
 * for a map to contain itself as a value, extreme caution is advised: the equals and hashCode methods are no longer well 
 * defined on a such a map.
 * 
 * All general-purpose map implementation classes should provide two "standard" constructors: a void (no arguments) 
 * constructor which creates an empty map, and a constructor with a single argument of type Map, which creates a new map 
 * with the same key-value mappings as its argument. In effect, the latter constructor allows the user to copy any map, 
 * producing an equivalent map of the desired class. There is no way to enforce this recommendation (as interfaces cannot 
 * contain constructors) but all of the general-purpose map implementations in the JDK comply.
 * 
 * The "destructive" methods contained in this interface, that is, the methods that modify the map on which they operate, 
 * are specified to throw UnsupportedOperationException if this map does not support the operation. If this is the case, 
 * these methods may, but are not required to, throw an UnsupportedOperationException if the invocation would have no effect 
 * on the map. For example, invoking the putAll(Map) method on an unmodifiable map may, but is not required to, throw the 
 * exception if the map whose mappings are to be "superimposed" is empty.
 * 
 * Some map implementations have restrictions on the keys and values they may contain. For example, some implementations 
 * prohibit null keys and values, and some have restrictions on the types of their keys. Attempting to insert an ineligible 
 * key or value throws an unchecked exception, typically NullPointerException or ClassCastException. Attempting to query 
 * the presence of an ineligible key or value may throw an exception, or it may simply return false; some implementations 
 * will exhibit the former behavior and some will exhibit the latter. More generally, attempting an operation on an ineligible 
 * key or value whose completion would not result in the insertion of an ineligible element into the map may throw an 
 * exception or it may succeed, at the option of the implementation. Such exceptions are marked as "optional" in the specification 
 * for this interface.
 * 
 * This interface is a member of the PHP Collections Framework.
 * 
 * Many methods in Collections Framework interfaces are defined in terms of the equals method. For example, the specification 
 * for the contains(Object key) method says: "returns true if and only if this map contain a mapping for a key k such that 
 * (key==null ? k==null : key.equals(k))." This specification should not be construed to imply that invoking Map.containsKey 
 * with a non-null argument key will cause key.equals(k) to be invoked for any key k. Implementations are free to implement 
 * optimizations whereby the equals invocation is avoided, for example, by first comparing the hash codes of the two keys. 
 * (The Object.hashCode() specification guarantees that two objects with unequal hash codes cannot be equal.) More generally,
 * implementations of the various Collections Framework interfaces are free to take advantage of the specified behavior of underlying 
 * Object methods wherever the implementor deems it appropriate. 
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Map.php 14 2006-11-28 22:05:19Z rdff3 $
 */
interface Map {

	/**
	 * Removes all mappings from this map.
	 *
	 * @throws {@link UnsupportedOperationException} - clear is not supported by this map.
	 */
	public function clear();
	
	/**
	 * Returns true if this map contains a mapping for the specified key.
	 *
	 * Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map 
	 * contains a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)
	 *
	 * @parameter Object $key key whose presence in this map is to be tested.
	 * @returns boolean true if this map contains a mapping for the specified key.
	 * @throws {@link ClassCastException} - if the key is of an inappropriate type for this map.
	 * @throws {@link NullPointerException} - if the key is null and this map does not permit null keys.
	 */
	public function containsKey( Object $key );
	
	/**
	 * Returns true if this map maps one or more keys to the specified value.
	 *
	 * Returns true if this map maps one or more keys to the specified value. More formally, returns true if and only if this map 
	 * contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will 
	 * probably require time linear in the map size for most implementations of the Map interface.
	 *
	 * @parameter Object $value value whose presence in this map is to be tested.
	 * @returns boolean true if this map maps one or more keys to the specified value.
	 * @throws {@link ClassCastException} - if the key is of an inappropriate type for this map.
	 * @throws {@link NullPointerException} - if the key is null and this map does not permit null keys.
	 */
	public function containsValue( Object $value );
		
	/**
	 * Compares the specified object with this map for equality.
	 *
	 * Compares the specified object with this map for equality. Returns true if the given object is also a map and the 
	 * two Maps represent the same mappings. More formally, two maps t1 and t2 represent the same mappings if
	 * t1.entrySet().equals(t2.entrySet()). This ensures that the equals method works properly across different implementations 
	 * of the Map interface.
	 *
	 * @parameter Object $o object to be compared for equality with this map.
	 * @returns boolean true if the specified object is equal to this map.
	 * @see Object::hashCode
	 */
	public function equals( Object $o );
	
	/**
	 * Returns the value to which this map maps the specified key.
	 *
	 * Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A 
	 * return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that 
	 * the map explicitly maps the key to null. The containsKey  operation may be used to distinguish these two cases.
	 *
	 * More formally, if this map contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), 
	 * then this method returns v; otherwise it returns null. (There can be at most one such mapping.) 
	 *
	 * @parameter Object $key key whose associated value is to be returned.
	 * @returns Object true the value to which this map maps the specified key, or null if the map contains no mapping for this key.
	 * @throws {@link ClassCastException} - if the key is of an inappropriate type for this map.
	 * @throws {@link NullPointerException} - if the key is null and this map does not permit null keys.
	 * @see containsKey
	 */
	public function get( Object $key );
	
	/**
	 * Returns the hash code value for this map.
	 *
	 * Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hashCodes of each entry 
	 * in the map's entrySet view. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two maps t1 
	 * and t2, as required by the general contract of Object.hashCode.
	 *
	 * @returns int the hash code value for this map.
	 */
	public function hashCode();
	
	/**
	 * Returns true if this map contains no key-value mappings.
	 *
	 * @returns boolean true if this map contains no key-value mappings.
	 */
	public function isEmpty();
	
	/**
	 * Returns a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected 
	 * in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the 
	 * iterator's own remove  operation), the results of the iteration are undefined. The set supports element removal, which 
	 * removes the corresponding mapping from the map, via the CollectionIterator.remove, Set.remove, removeAll retainAll, and clear operations. 
	 * It does not support the add or addAll operations.
	 *
	 * @returns Set a set view of the keys contained in this map.
	 */
	public function keySet();
	
	/**
	 * Associates the specified value with the specified key in this map.
	 *
	 * Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, 
	 * the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if 
	 * m.containsKey(k) would return true.))
	 *
	 * @parameter Comparable $key key with which the specified value is to be associated.
	 * @parameter Object $value value to be associated with the specified key.
	 * @returns Object previous value associated with specified key, or null  if there was no mapping for key. A null return 
	 * 		can also indicate that the map previously associated null  with the specified key, if the implementation supports null values.
	 * @throws {@link UnsupportedOperationException} - if the put operation is not supported by this map. 
	 * @throws {@link ClassCastException} - if the class of the specified key or value prevents it from being stored in this map. 
     * @throws {@link IllegalArgumentException} - if some aspect of this key or value prevents it from being stored in this map. 
     * @throws {@link NullPointerException} - if this map does not permit null keys or values, and the specified key or value is null.
	 */
	public function put( Object $key, Object $value );
	
	/**
	 * Copies all of the mappings from the specified map to this map.
	 *
	 * Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to
	 * that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of 
	 * this operation is unspecified if the specified map is modified while the operation is in progress.
	 *
	 * @parameter Map $t Mappings to be stored in this map.
	 * @throws {@link UnsupportedOperationException} - if the putAll method is not supported by this map.
	 * @throws {@link ClassCastException} - if the class of a key or value in the specified map prevents it from being stored 
	 *		in this map.
     * @throws {@link IllegalArgumentException} - some aspect of a key or value in the specified map prevents it from being stored 
	 *		in this map.
     * @throws {@link NullPointerException} - if the specified map is null, or if this map does not permit null keys or values, 
	 *		and the specified map contains null keys or values.
	 */
	public function putAll( Map $t );
	
	/**
	 * Removes the mapping for this key from this map if it is present.
	 *
	 * Removes the mapping for this key from this map if it is present. More formally, if this map contains a mapping from key k 
	 * to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can contain at most one 
	 * such mapping.)
	 *
	 * Returns the value to which the map previously associated the key, or null if the map contained no mapping for this key. 
	 * (A null return can also indicate that the map previously associated null with the specified key if the implementation 
	 * supports null values.) The map will not contain a mapping for the specified key once the call returns. 
	 *
	 * @parameter Object $key key whose mapping is to be removed from the map.
	 * @returns Object previous value associated with specified key, or null  if there was no mapping for key.
	 * @throws {@link ClassCastException} - if the key is of an inappropriate type for this map (optional). 
     * @throws {@link NullPointerException} - if the key is null and this map does not permit null keys (optional). 
     * @throws {@link UnsupportedOperationException} - if the remove method is not supported by this map.
	 */
	public function remove( Object $key );
	
	/**
	 * Returns the number for key-value mappings in this map.
	 *
	 * @returns int the number of key-value mappings in this map
	 */
	public function size();
	
	/**
	 * Returns a collection view of the values contained in this map. 
	 *
	 * Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map 
	 * are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in 
	 * progress (except through the iterator's own remove operation), the results of the iteration are undefined. The collection 
	 * supports element removal, which removes the corresponding mapping from the map, via the CollectionIterator.remove, Collection.remove,
	 * removeAll, retainAll and clear operations. It does not support the add or addAll operations.
	 *
	 * @returns Collection a collection view of the values contained in this map.
	 */
	public function values();
}


?>